https://gateway.iugu.com/api/v1/transactions/cancel/{payment_id}
Cancelar um pagamento
Cancela ou reembolsa um pagamento previamente capturado ou autorizado.
────────────────────────────────────────────────────────────────────────────────
CANCELAMENTO TOTAL:
Para cancelar o valor total, envie amount_cents com o valor total do pagamento. O parâmetro é obrigatório: se ausente, a resposta é 400 invalid_amount.
Se o pagamento já foi totalmente reembolsado, retorna 200 com o estado atual do pagamento, sem nova chamada ao adquirente.
────────────────────────────────────────────────────────────────────────────────
CANCELAMENTO PARCIAL:
É possível cancelar parcialmente um pagamento. A soma de todos os cancelamentos não pode exceder o valor original. Autorizações só podem ser canceladas com o valor total (cancelamento parcial não é permitido).
────────────────────────────────────────────────────────────────────────────────
RESTRIÇÕES:
- Valores devem ser maiores que zero.
- Prazo máximo de cancelamento configurável por workspace.
- Limite de taxa (quando habilitado): máximo de 1 requisição por hora por payment_id.
────────────────────────────────────────────────────────────────────────────────
POLÍTICAS ESPECÍFICAS POR ADQUIRENTE:
- Getnet: Cancelamento parcial no mesmo dia (D0) não é permitido
- Outras restrições podem variar por adquirente (Cielo, Rede)
Sem ações implementadas definidas
Request
|
Path variables |
|
|---|---|
|
payment_id
Required Type: string ID do pagamento a ser cancelado |
|
|
Headers |
|
|---|---|
|
Workspace-Id
Type: string ID do workspace. Quando ausente, é usado o workspace padrão do Gateway. Ex: 1D81KhKbYuVq9505Bz4Nk9 |
|
|
Body Required Content Type: application/json |
||||||
|---|---|---|---|---|---|---|
|
||||||
1
2
3
4
5
{
"amount_cents": 5000,
"account_info": {
}
}
Response
|
200 |
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
|
Pagamento cancelado com sucesso (ou já totalmente reembolsado)
|
||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
{
"payment": {
"id": "<ID>",
"status": "<STATUS>",
"multi": [
"<MULTI>"
],
"success_ec": "<SUCCESS_EC>",
"mcc": "<MCC>",
"recurrent": "<RECURRENT>",
"card_on_file": "<CARD_ON_FILE>",
"tid": "<TID>",
"nsu": "<NSU>",
"authorization_code": "<AUTHORIZATION_CODE>",
"amount_cents": "<AMOUNT_CENTS>",
"refunded_amount_cents": "<REFUNDED_AMOUNT_CENTS>",
"cnpj": "<CNPJ>",
"workspace_id": "<WORKSPACE_ID>",
"account_id": "<ACCOUNT_ID>",
"invoice_id": "<INVOICE_ID>",
"client_ref": "<CLIENT_REF>",
"subscription_id": "<SUBSCRIPTION_ID>",
"card_id": "<CARD_ID>",
"card_bin": "<CARD_BIN>",
"card_last_four": "<CARD_LAST_FOUR>",
"currency": "<CURRENCY>",
"installments": "<INSTALLMENTS>",
"soft_descriptor": "<SOFT_DESCRIPTOR>",
"created_at": "<CREATED_AT>",
"updated_at": "<UPDATED_AT>",
"transactions": [
{
"id": "<ID>",
"function": "<FUNCTION>",
"success": "<SUCCESS>",
"tid": "<TID>",
"nsu": "<NSU>",
"arp": "<ARP>",
"acquirer": {
"payment_id": "<PAYMENT_ID>",
"status_code": "<STATUS_CODE>",
"acquirer_mac_code": "<ACQUIRER_MAC_CODE>",
"status_description": "<STATUS_DESCRIPTION>",
"request_status_code": "<REQUEST_STATUS_CODE>",
"request_status_description": "<REQUEST_STATUS_DESCRIPTION>"
},
"lr": {
"code": "<CODE>",
"source": "<SOURCE>"
},
"card_id": "<CARD_ID>",
"card_bin": "<CARD_BIN>",
"card_last_four": "<CARD_LAST_FOUR>",
"card_on_file": "<CARD_ON_FILE>",
"transaction_token_type": "<TRANSACTION_TOKEN_TYPE>",
"amount_cents": "<AMOUNT_CENTS>",
"ec_group": {
"id": "<ID>",
"name": "<NAME>"
},
"commercial_enterprise": {
"id": "<ID>",
"name": "<NAME>",
"number": "<NUMBER>",
"acquirer": "<ACQUIRER>",
"mcc": {
"id": "<ID>",
"code": "<CODE>",
"description": "<DESCRIPTION>"
}
},
"created_at": "<CREATED_AT>"
}
],
"anti_fraud": [
{
"id": "<ID>",
"payment_id": "<PAYMENT_ID>",
"provider": "feedzai",
"provider_id": "<PROVIDER_ID>",
"decision": "<DECISION>",
"omniscore": "<OMNISCORE>",
"created_at": "<CREATED_AT>"
}
]
}
}
|
400 |
|
|---|---|
|
Requisição inválida. Possíveis causas: - `invalid_parameter_error`: parâmetro com tipo inválido ou não documentado - `invalid_amount`: `amount_cents` ausente, zero ou negativo - `payment_cannot_be_canceled`: o adquirente (Cielo) informou que o pagamento não está em estado que permite cancelamento - `bad_request`: o adquirente rejeitou o cancelamento (`details` traz a resposta do adquirente) |
|
1
"<SCHEMA>"
|
401 |
||
|---|---|---|
|
Não autorizado - Token de autenticação inválido ou ausente
|
||
1
2
3
{
"message": "<MESSAGE>"
}
|
404 |
||||||||
|---|---|---|---|---|---|---|---|---|
|
Recurso não encontrado. Possíveis causas: - `payment_not_found`: Pagamento com o ID informado não existe - `payment_transaction_not_found`: Transação cancelável do pagamento não encontrada - `commercial_enterprise_not_found`: Estabelecimento comercial da transação não encontrado
|
||||||||
1
2
3
4
5
6
{
"error": "payment_not_found",
"service": "Acquirers::CancelService",
"details": {
}
}
|
409 |
||||||||
|---|---|---|---|---|---|---|---|---|
|
`payment_processing_in_progress`: outra requisição para o mesmo pagamento está em processamento; tente novamente
|
||||||||
1
2
3
4
5
6
{
"error": "payment_not_found",
"service": "Acquirers::CancelService",
"details": {
}
}
|
422 |
||||||||
|---|---|---|---|---|---|---|---|---|
|
Erro de validação ou política. Possíveis causas: - `amount_not_permitted`: Valor solicitado excede o disponível para cancelamento - `authorization_cannot_be_partially_canceled`: Autorizações só podem ser canceladas totalmente - `cancellation_deadline_exceeded`: Prazo máximo para cancelamento foi excedido - `deny_getnet_D0_partial_refund`: Getnet não permite cancelamento parcial no mesmo dia (D0) - `deny_rede_D0_partial_refund`: Rede não permite cancelamento parcial no mesmo dia (D0) - `deny_rede_elo_D0_refund`: Rede não permite cancelamento de transação Elo no mesmo dia (D0), nem total nem parcial - `no_successful_transaction_to_cancel`: O pagamento não possui transação bem-sucedida cancelável - `cannot_create_payment_transaction`: Falha ao registrar a transação de cancelamento
|
||||||||
1
2
3
4
5
6
{
"error": "payment_not_found",
"service": "Acquirers::CancelService",
"details": {
}
}
|
429 |
||||
|---|---|---|---|---|
|
Limite de taxa excedido Quando o limite está habilitado, apenas 1 requisição de cancelamento por hora é permitida para cada payment_id. A cota é consumida por qualquer requisição autenticada, inclusive as que retornam erro.
|
||||
1
2
3
4
{
"error": "<ERROR>",
"message": "Rate limit exceeded. Try again later."
}
|
500 |
||||||||
|---|---|---|---|---|---|---|---|---|
|
Erro interno do servidor. Possíveis causas: - `payment_cancelation_error`: Erro inesperado ao aplicar as políticas de cancelamento - Outros erros inesperados durante o processamento. Entre em contato com o suporte se o problema persistir.
|
||||||||
1
2
3
4
5
6
{
"error": "payment_not_found",
"service": "Acquirers::CancelService",
"details": {
}
}